<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <title>Hoodoo::Presenters::BaseDSL</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <link rel="stylesheet" href="../../../css/reset.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../../css/main.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../../css/github.css" type="text/css" media="screen" />
<script src="../../../js/jquery-1.3.2.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/jquery-effect.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/main.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/highlight.pack.js" type="text/javascript" charset="utf-8"></script>

</head>

<body>
    <div class="banner">
        <h1>
            <span class="type">Module</span>
            Hoodoo::Presenters::BaseDSL
        </h1>
        <ul class="files">
            <li><a href="../../../files/lib/hoodoo/presenters/base_dsl_rb.html">lib/hoodoo/presenters/base_dsl.rb</a></li>
        </ul>
    </div>
    <div id="bodyContent">
        <div id="content">
    <div class="description">
      
<p>A mixin to be used by any presenter that wants to support the <a
href="../Presenters.html">Hoodoo::Presenters</a> family of schema DSL
methods. See e.g. <a href="Base.html">Hoodoo::Presenters::Base</a>. Mixed
in by e.g. <a href="Object.html">Hoodoo::Presenters::Object</a> so that an
instance can nest definitions of fields inside itself using this DSL.</p>

    </div>








    <!-- Method ref -->
    <div class="sectiontitle">Methods</div>
    <dl class="methods">
        <dt>A</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-array">array</a>
              </li>
          </ul>
        </dd>
        <dt>B</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-boolean">boolean</a>
              </li>
          </ul>
        </dd>
        <dt>D</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-date">date</a>,
              </li>
              <li>
                <a href="#method-i-datetime">datetime</a>,
              </li>
              <li>
                <a href="#method-i-decimal">decimal</a>
              </li>
          </ul>
        </dd>
        <dt>E</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-enum">enum</a>
              </li>
          </ul>
        </dd>
        <dt>F</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-float">float</a>
              </li>
          </ul>
        </dd>
        <dt>H</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-hash">hash</a>
              </li>
          </ul>
        </dd>
        <dt>I</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-integer">integer</a>,
              </li>
              <li>
                <a href="#method-i-internationalised">internationalised</a>,
              </li>
              <li>
                <a href="#method-i-is_internationalised-3F">is_internationalised?</a>
              </li>
          </ul>
        </dd>
        <dt>O</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-object">object</a>
              </li>
          </ul>
        </dd>
        <dt>R</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-resource">resource</a>
              </li>
          </ul>
        </dd>
        <dt>S</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-string">string</a>
              </li>
          </ul>
        </dd>
        <dt>T</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-tags">tags</a>,
              </li>
              <li>
                <a href="#method-i-text">text</a>,
              </li>
              <li>
                <a href="#method-i-type">type</a>
              </li>
          </ul>
        </dd>
        <dt>U</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-uuid">uuid</a>
              </li>
          </ul>
        </dd>
    </dl>










    <!-- Methods -->
      <div class="sectiontitle">Instance Public methods</div>
        <div class="method">
          <div class="title method-title" id="method-i-array">
              <b>array</b>( name, options = {}, &amp;block )
            <a href="../../../classes/Hoodoo/Presenters/BaseDSL.html#method-i-array" name="method-i-array" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Define a JSON array with the supplied name and options. If there is a block
provided, then more DSL calls inside the block define how each array entry
must look; otherwise array entries are not validated / are undefined.</p>

<p>When an array field uses +:required =&gt; true+, this only says that at
least an empty array must be present, nothing more. If the array uses a
block with fields that themselves are required, then this is only checked
for if the array contains one or more entries (and is checked for each of
those entries).</p>
<dl class="rdoc-list note-list"><dt><code>name</code>
<dd>
<p>The JSON key</p>
</dd><dt><code>options</code>
<dd>
<p>A <code>Hash</code> of options, e.g. :required =&gt; true</p>
</dd><dt>&amp;block
<dd>
<p>Optional block declaring the fields of each array item</p>
</dd></dl>

<p>Example - mandatory JSON field “currencies” would lead to an array where
each array entry contains the fields defined by
Hoodoo::Data::Types::Currency along with an up-to-32 character string with
field name “notes”, that field also being required. Whether or not the
fields of the referenced Currency type are needed is up to the definition
of that type. See <a href="BaseDSL.html#method-i-type">type</a> for more
information.</p>

<pre><code>class VeryWealthy &lt; Hoodoo::Presenters::Base
  schema do
    array :currencies, :required =&gt; true do
      type :Currency
      string :notes, :required =&gt; true, :length =&gt; 32
    end
  end
end
</code></pre>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-array_source')" id="l_method-i-array_source">show</a>
              </p>
              <div id="method-i-array_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/presenters/base_dsl.rb, line 82</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">array</span>( <span class="ruby-identifier">name</span>, <span class="ruby-identifier">options</span> = {}, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span> )
  <span class="ruby-identifier">ary</span> = <span class="ruby-identifier">property</span>( <span class="ruby-identifier">name</span>, <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Presenters</span><span class="ruby-operator">::</span><span class="ruby-constant">Array</span>, <span class="ruby-identifier">options</span>, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span> )
  <span class="ruby-identifier">internationalised</span>() <span class="ruby-keyword">if</span> <span class="ruby-identifier">ary</span>.<span class="ruby-identifier">is_internationalised?</span>()
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-boolean">
              <b>boolean</b>( name, options = {} )
            <a href="../../../classes/Hoodoo/Presenters/BaseDSL.html#method-i-boolean" name="method-i-boolean" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Define a JSON boolean with the supplied name and options.</p>
<dl class="rdoc-list note-list"><dt>name
<dd>
<p>The JSON key</p>
</dd><dt>options
<dd>
<p>A <code>Hash</code> of options, e.g. :required =&gt; true</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-boolean_source')" id="l_method-i-boolean_source">show</a>
              </p>
              <div id="method-i-boolean_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/presenters/base_dsl.rb, line 177</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">boolean</span>( <span class="ruby-identifier">name</span>, <span class="ruby-identifier">options</span> = {} )
  <span class="ruby-identifier">property</span>( <span class="ruby-identifier">name</span>, <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Presenters</span><span class="ruby-operator">::</span><span class="ruby-constant">Boolean</span>, <span class="ruby-identifier">options</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-date">
              <b>date</b>( name, options = {} )
            <a href="../../../classes/Hoodoo/Presenters/BaseDSL.html#method-i-date" name="method-i-date" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Define a JSON date with the supplied name and options.</p>
<dl class="rdoc-list note-list"><dt>name
<dd>
<p>The JSON key</p>
</dd><dt>options
<dd>
<p>A <code>Hash</code> of options, e.g. :required =&gt; true</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-date_source')" id="l_method-i-date_source">show</a>
              </p>
              <div id="method-i-date_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/presenters/base_dsl.rb, line 186</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">date</span>( <span class="ruby-identifier">name</span>, <span class="ruby-identifier">options</span> = {} )
  <span class="ruby-identifier">property</span>( <span class="ruby-identifier">name</span>, <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Presenters</span><span class="ruby-operator">::</span><span class="ruby-constant">Date</span>, <span class="ruby-identifier">options</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-datetime">
              <b>datetime</b>( name, options = {} )
            <a href="../../../classes/Hoodoo/Presenters/BaseDSL.html#method-i-datetime" name="method-i-datetime" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Define a JSON datetime with the supplied name and options.</p>
<dl class="rdoc-list note-list"><dt>name
<dd>
<p>The JSON key</p>
</dd><dt>options
<dd>
<p>A <code>Hash</code> of options, e.g. :required =&gt; true</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-datetime_source')" id="l_method-i-datetime_source">show</a>
              </p>
              <div id="method-i-datetime_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/presenters/base_dsl.rb, line 195</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">datetime</span>( <span class="ruby-identifier">name</span>, <span class="ruby-identifier">options</span> = {} )
  <span class="ruby-identifier">property</span>( <span class="ruby-identifier">name</span>, <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Presenters</span><span class="ruby-operator">::</span><span class="ruby-constant">DateTime</span>, <span class="ruby-identifier">options</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-decimal">
              <b>decimal</b>( name, options = {} )
            <a href="../../../classes/Hoodoo/Presenters/BaseDSL.html#method-i-decimal" name="method-i-decimal" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Define a JSON decimal with the supplied name and options.</p>
<dl class="rdoc-list note-list"><dt>name
<dd>
<p>The JSON key</p>
</dd><dt>options
<dd>
<p>A <code>Hash</code> of options, e.g. :required =&gt; true, :precision =&gt;
10</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-decimal_source')" id="l_method-i-decimal_source">show</a>
              </p>
              <div id="method-i-decimal_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/presenters/base_dsl.rb, line 168</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">decimal</span>( <span class="ruby-identifier">name</span>, <span class="ruby-identifier">options</span> = {} )
  <span class="ruby-identifier">property</span>( <span class="ruby-identifier">name</span>, <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Presenters</span><span class="ruby-operator">::</span><span class="ruby-constant">Decimal</span>, <span class="ruby-identifier">options</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-enum">
              <b>enum</b>( name, options = {} )
            <a href="../../../classes/Hoodoo/Presenters/BaseDSL.html#method-i-enum" name="method-i-enum" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Define a JSON string which can only have a restricted set of exactly
matched values, with the supplied name and options.</p>
<dl class="rdoc-list note-list"><dt><code>name</code>
<dd>
<p>The JSON key</p>
</dd><dt><code>options</code>
<dd>
<p>A <code>Hash</code> of options, e.g. :required =&gt; true and mandatory
:from =&gt; [array-of-allowed-strings-or-symbols]</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-enum_source')" id="l_method-i-enum_source">show</a>
              </p>
              <div id="method-i-enum_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/presenters/base_dsl.rb, line 216</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">enum</span>( <span class="ruby-identifier">name</span>, <span class="ruby-identifier">options</span> = {} )
  <span class="ruby-identifier">property</span>( <span class="ruby-identifier">name</span>, <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Presenters</span><span class="ruby-operator">::</span><span class="ruby-constant">Enum</span>, <span class="ruby-identifier">options</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-float">
              <b>float</b>( name, options = {} )
            <a href="../../../classes/Hoodoo/Presenters/BaseDSL.html#method-i-float" name="method-i-float" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Define a JSON float with the supplied name and options.</p>
<dl class="rdoc-list note-list"><dt>name
<dd>
<p>The JSON key</p>
</dd><dt>options
<dd>
<p>A <code>Hash</code> of options, e.g. :required =&gt; true</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-float_source')" id="l_method-i-float_source">show</a>
              </p>
              <div id="method-i-float_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/presenters/base_dsl.rb, line 159</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">float</span>( <span class="ruby-identifier">name</span>, <span class="ruby-identifier">options</span> = {} )
  <span class="ruby-identifier">property</span>( <span class="ruby-identifier">name</span>, <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Presenters</span><span class="ruby-operator">::</span><span class="ruby-constant">Float</span>, <span class="ruby-identifier">options</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-hash">
              <b>hash</b>( name, options = {}, &amp;block )
            <a href="../../../classes/Hoodoo/Presenters/BaseDSL.html#method-i-hash" name="method-i-hash" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Define a JSON object with the supplied name and optional constraints on
properties (like hash keys) and property values (like hash values) that the
object may contain, in abstract terms.</p>
<dl class="rdoc-list note-list"><dt><code>name</code>
<dd>
<p>The JSON key</p>
</dd><dt><code>options</code>
<dd>
<p>A <code>Hash</code> of options, e.g. :required =&gt; true</p>
</dd><dt>&amp;block
<dd>
<p>Optional block declaring the fields making up the nested hash</p>
</dd></dl>

<p>Example 1 - a <a href="Hash.html">Hash</a> where keys must be &lt;= 16
characters long and values</p>

<pre><code>        must match the Hoodoo::Data::Types::Currency type.

class CurrencyHash &lt; Hoodoo::Presenters::Base
  schema do
    hash :currencies do
      keys :length =&gt; 16 do
        type :Currency
      end
    end
  end
end</code></pre>

<p>See <a href="Hash.html#method-i-keys">Hoodoo::Presenters::Hash#keys</a> for
more information and examples.</p>

<p>Example 2 - a <a href="Hash.html">Hash</a> where keys must be &#39;one&#39;
or &#39;two&#39;, each with a</p>

<pre><code>        value matching the given schema.

class AltCurrencyHash &lt; Hoodoo::Presenters::Base
  schema do
    hash :currencies do
      key :one do
        type :Currency
      end

      key :two do
        text :title
        text :description
      end
    end
  end
end</code></pre>

<p>See <a href="Hash.html#method-i-key">Hoodoo::Presenters::Hash#key</a> for
more information and examples.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-hash_source')" id="l_method-i-hash_source">show</a>
              </p>
              <div id="method-i-hash_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/presenters/base_dsl.rb, line 131</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">hash</span>( <span class="ruby-identifier">name</span>, <span class="ruby-identifier">options</span> = {}, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span> )
  <span class="ruby-identifier">hash</span> = <span class="ruby-identifier">property</span>( <span class="ruby-identifier">name</span>, <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Presenters</span><span class="ruby-operator">::</span><span class="ruby-constant">Hash</span>, <span class="ruby-identifier">options</span>, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span> )
  <span class="ruby-identifier">internationalised</span>() <span class="ruby-keyword">if</span> <span class="ruby-identifier">hash</span>.<span class="ruby-identifier">is_internationalised?</span>()
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-integer">
              <b>integer</b>( name, options = {} )
            <a href="../../../classes/Hoodoo/Presenters/BaseDSL.html#method-i-integer" name="method-i-integer" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Define a JSON integer with the supplied name and options.</p>
<dl class="rdoc-list note-list"><dt>name
<dd>
<p>The JSON key</p>
</dd><dt>options
<dd>
<p>A <code>Hash</code> of options, e.g. :required =&gt; true</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-integer_source')" id="l_method-i-integer_source">show</a>
              </p>
              <div id="method-i-integer_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/presenters/base_dsl.rb, line 141</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">integer</span>( <span class="ruby-identifier">name</span>, <span class="ruby-identifier">options</span> = {} )
  <span class="ruby-identifier">property</span>( <span class="ruby-identifier">name</span>, <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Presenters</span><span class="ruby-operator">::</span><span class="ruby-constant">Integer</span>, <span class="ruby-identifier">options</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-internationalised">
              <b>internationalised</b>( options = nil )
            <a href="../../../classes/Hoodoo/Presenters/BaseDSL.html#method-i-internationalised" name="method-i-internationalised" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Declares that this Type or Resource contains fields which will may carry
human-readable data subject to platform interntionalisation rules. A
Resource which is internationalised automatically gains a
<code>language</code> field (part of the Platform API&#39;s Common Fields)
used in resource representations. A Type which is internationalised gains
nothing until it is cross-referenced by a Resource definion, at which point
the cross-referencing resource becomes itself implicitly internationalised
(so it “taints” the resource). For cross-referencing, see <a
href="BaseDSL.html#method-i-type">type</a>.</p>
<dl class="rdoc-list note-list"><dt><code>options</code>
<dd>
<p>Optional options hash. No options currently defined.</p>
</dd></dl>

<p>Example - a Member resource with internationalised fields such as the
member&#39;s name:</p>

<pre><code>class Member &lt; Hoodoo::Presenters::Base
  schema do

    # Say that Member will contain at least one field that holds
    # human readable data, causing the Member to be subject to
    # internationalisation rules.

    internationalised

    # Declare fields as normal, for example...

    text :name

  end
end
</code></pre>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-internationalised_source')" id="l_method-i-internationalised_source">show</a>
              </p>
              <div id="method-i-internationalised_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/presenters/base_dsl.rb, line 485</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">internationalised</span>( <span class="ruby-identifier">options</span> = <span class="ruby-keyword">nil</span> )
  <span class="ruby-identifier">options</span> <span class="ruby-operator">||=</span> {}
  <span class="ruby-ivar">@internationalised</span> = <span class="ruby-keyword">true</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-is_internationalised-3F">
              <b>is_internationalised?</b>()
            <a href="../../../classes/Hoodoo/Presenters/BaseDSL.html#method-i-is_internationalised-3F" name="method-i-is_internationalised-3F" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>An enquiry method related to, but not part of the DSL; returns
<code>true</code> if the schema instance is internationalised, else
<code>false</code>.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-is_internationalised-3F_source')" id="l_method-i-is_internationalised-3F_source">show</a>
              </p>
              <div id="method-i-is_internationalised-3F_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/presenters/base_dsl.rb, line 493</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">is_internationalised?</span>
  <span class="ruby-operator">!</span><span class="ruby-operator">!</span> <span class="ruby-ivar">@internationalised</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-object">
              <b>object</b>( name, options = {}, &amp;block )
            <a href="../../../classes/Hoodoo/Presenters/BaseDSL.html#method-i-object" name="method-i-object" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Define a JSON object with the supplied name and options.</p>
<dl class="rdoc-list note-list"><dt>name
<dd>
<p>The JSON key.</p>
</dd><dt>options
<dd>
<p>Optional <code>Hash</code> of options, e.g. :required =&gt; true</p>
</dd><dt>&amp;block
<dd>
<p>Block declaring the fields making up the nested object</p>
</dd></dl>

<p>Example - mandatory JSON field “currencies” would lead to an object which
had the same fields as Hoodoo::Data::Types::Currency along with an up-to-32
character string with field name “notes”, that field also being required.
Whether or not the fields of the referenced Currency type are needed is up
to the definition of that type. See <a
href="BaseDSL.html#method-i-type">type</a> for more information.</p>

<pre><code>class Wealthy &lt; Hoodoo::Presenters::Base
  schema do
    object :currencies, :required =&gt; true do
      type :Currency
      string :notes, :required =&gt; true, :length =&gt; 32
    end
  end
end
</code></pre>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-object_source')" id="l_method-i-object_source">show</a>
              </p>
              <div id="method-i-object_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/presenters/base_dsl.rb, line 44</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">object</span>( <span class="ruby-identifier">name</span>, <span class="ruby-identifier">options</span> = {}, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span> )
  <span class="ruby-identifier">raise</span> <span class="ruby-constant">ArgumentError</span>.<span class="ruby-identifier">new</span>( <span class="ruby-string">&#39;Hoodoo::Presenters::Base#Object must have block&#39;</span> ) <span class="ruby-keyword">unless</span> <span class="ruby-identifier">block_given?</span>

  <span class="ruby-identifier">obj</span> = <span class="ruby-identifier">property</span>( <span class="ruby-identifier">name</span>, <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Presenters</span><span class="ruby-operator">::</span><span class="ruby-constant">Object</span>, <span class="ruby-identifier">options</span>, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span> )
  <span class="ruby-identifier">internationalised</span>() <span class="ruby-keyword">if</span> <span class="ruby-identifier">obj</span>.<span class="ruby-identifier">is_internationalised?</span>()
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-resource">
              <b>resource</b>( resource_info, options = nil )
            <a href="../../../classes/Hoodoo/Presenters/BaseDSL.html#method-i-resource" name="method-i-resource" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Declare that a resource of a given name is included at this point. This is
only normally done within the description of the schema for an interface.
The fields of the given named resource are considered to be defined inline
at the point of declaration - essentially, it&#39;s macro expansion.</p>
<dl class="rdoc-list note-list"><dt><code>resource_info</code>
<dd>
<p>The <a href="Base.html">Hoodoo::Presenters::Base</a> subclass for the
Resource in question, e.g. <code>Product</code>. The deprecated form of
this interface takes the name of the type to nest as a symbol, e.g.
<code>:Product</code>, in which case the Resource must be declared within
nested modules “Hoodoo::Data::Types”.</p>
</dd><dt><code>options</code>
<dd>
<p>Optional options hash. No options currently defined.</p>
</dd></dl>

<p>Example - an iterface takes an <code>Outlet</code> resource in its create
action.</p>

<pre><code>class Outlet &lt; Hoodoo::Presenters::Base
  schema do
    internationalised

    text :name
    uuid :participant_id, :resource =&gt; :Participant, :required =&gt; true
    uuid :calculator_id,  :resource =&gt; :Calculator
  end
end

class OutletInterface &lt; Hoodoo::Services::Interface
  to_create do
    resource Outlet
  end
end
</code></pre>

<p>It doesn&#39;t make sense to mark a <code>resource</code> &#39;field&#39;
as <code>:required</code> in the options since the declaration just expands
to the contents of the referenced resource and it is the definition of that
resource that determines whether or not its various field(s) are optional /
required. That is, the following two declarations behave identically:</p>

<pre><code>resource Outlet

resource Outlet, :required =&gt; true # Pointless option!
</code></pre>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-resource_source')" id="l_method-i-resource_source">show</a>
              </p>
              <div id="method-i-resource_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/presenters/base_dsl.rb, line 438</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">resource</span>( <span class="ruby-identifier">resource_info</span>, <span class="ruby-identifier">options</span> = <span class="ruby-keyword">nil</span> )
  <span class="ruby-identifier">options</span> <span class="ruby-operator">||=</span> {}

  <span class="ruby-keyword">if</span> <span class="ruby-identifier">resource_info</span>.<span class="ruby-identifier">is_a?</span>( <span class="ruby-constant">Class</span> ) <span class="ruby-operator">&amp;&amp;</span> <span class="ruby-identifier">resource_info</span> <span class="ruby-operator">&lt;</span> <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Presenters</span><span class="ruby-operator">::</span><span class="ruby-constant">Base</span>
    <span class="ruby-identifier">klass</span> = <span class="ruby-identifier">resource_info</span>
  <span class="ruby-keyword">else</span>
    <span class="ruby-keyword">begin</span>
      <span class="ruby-identifier">klass</span> = <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Data</span><span class="ruby-operator">::</span><span class="ruby-constant">Resources</span>.<span class="ruby-identifier">const_get</span>( <span class="ruby-identifier">resource_info</span> )
    <span class="ruby-keyword">rescue</span>
      <span class="ruby-identifier">raise</span> <span class="ruby-node">&quot;Hoodoo::Presenters::Base\#resource: Unrecognised resource name &#39;#{ resource_info }&#39;&quot;</span>
    <span class="ruby-keyword">end</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">instance_exec</span>( <span class="ruby-operator">&amp;</span><span class="ruby-identifier">klass</span>.<span class="ruby-identifier">get_schema_definition</span>() )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-string">
              <b>string</b>( name, options = {} )
            <a href="../../../classes/Hoodoo/Presenters/BaseDSL.html#method-i-string" name="method-i-string" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Define a JSON string with the supplied name and options.</p>
<dl class="rdoc-list note-list"><dt>name
<dd>
<p>The JSON key</p>
</dd><dt>options
<dd>
<p>A <code>Hash</code> of options, e.g. :required =&gt; true, :length =&gt; 10</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-string_source')" id="l_method-i-string_source">show</a>
              </p>
              <div id="method-i-string_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/presenters/base_dsl.rb, line 150</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">string</span>( <span class="ruby-identifier">name</span>, <span class="ruby-identifier">options</span> = {} )
  <span class="ruby-identifier">property</span>( <span class="ruby-identifier">name</span>, <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Presenters</span><span class="ruby-operator">::</span><span class="ruby-constant">String</span>, <span class="ruby-identifier">options</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-tags">
              <b>tags</b>( field_name, options = nil )
            <a href="../../../classes/Hoodoo/Presenters/BaseDSL.html#method-i-tags" name="method-i-tags" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Declares that this Type or Resource has a string field of unlimited length
that contains comma-separated tag strings.</p>
<dl class="rdoc-list note-list"><dt><code>field_name</code>
<dd>
<p>Name of the field that will hold the tags.</p>
</dd><dt><code>options</code>
<dd>
<p>Optional options hash. See <a
href="BaseDSL.html">Hoodoo::Presenters::BaseDSL</a>.</p>
</dd></dl>

<p>Example - a Product resource which supports product tagging:</p>

<pre><code>class Product &lt; Hoodoo::Presenters::Base
  schema do
    internationalised

    text :name
    text :description
    string :sku, :length =&gt; 64
    tags :tags
  end
end
</code></pre>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-tags_source')" id="l_method-i-tags_source">show</a>
              </p>
              <div id="method-i-tags_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/presenters/base_dsl.rb, line 239</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">tags</span>( <span class="ruby-identifier">field_name</span>, <span class="ruby-identifier">options</span> = <span class="ruby-keyword">nil</span> )
  <span class="ruby-identifier">options</span> <span class="ruby-operator">||=</span> {}
  <span class="ruby-identifier">property</span>( <span class="ruby-identifier">field_name</span>, <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Presenters</span><span class="ruby-operator">::</span><span class="ruby-constant">Tags</span>, <span class="ruby-identifier">options</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-text">
              <b>text</b>( name, options = {} )
            <a href="../../../classes/Hoodoo/Presenters/BaseDSL.html#method-i-text" name="method-i-text" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Define a JSON string of unlimited length with the supplied name and
options.</p>
<dl class="rdoc-list note-list"><dt>name
<dd>
<p>The JSON key</p>
</dd><dt>options
<dd>
<p>A <code>Hash</code> of options, e.g. :required =&gt; true</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-text_source')" id="l_method-i-text_source">show</a>
              </p>
              <div id="method-i-text_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/presenters/base_dsl.rb, line 205</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">text</span>( <span class="ruby-identifier">name</span>, <span class="ruby-identifier">options</span> = {} )
  <span class="ruby-identifier">property</span>( <span class="ruby-identifier">name</span>, <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Presenters</span><span class="ruby-operator">::</span><span class="ruby-constant">Text</span>, <span class="ruby-identifier">options</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-type">
              <b>type</b>( type_info, options = nil )
            <a href="../../../classes/Hoodoo/Presenters/BaseDSL.html#method-i-type" name="method-i-type" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Declare that a nested type of a given name is included at this point. This
is only normally done within an <code>array</code> or <code>object</code>
declaration. The fields of the given named type are considered to be
defined inline at the point of declaration - essentially, it&#39;s macro
expansion.</p>
<dl class="rdoc-list note-list"><dt><code>type_info</code>
<dd>
<p>The <a href="Base.html">Hoodoo::Presenters::Base</a> subclass for the Type
in question, e.g. <code>BasketItem</code>. The deprecated form of this
interface takes the name of the type to nest as a symbol, e.g.
<code>:BasketItem</code>, in which case the Type must be declared within
nested modules “Hoodoo::Data::Types”.</p>
</dd><dt><code>options</code>
<dd>
<p>Optional options hash. No options currently defined.</p>
</dd></dl>

<p>It doesn&#39;t make sense to mark a <code>type</code> &#39;field&#39; as
<code>:required</code> in the options since the declaration just expands to
the contents of the referenced type and it is the definition of that type
that determines whether or not its various field(s) are optional or
required.</p>

<p>Example 1 - a basket includes an array of the Type described by class
<code>BasketItem</code>:</p>

<pre><code>class Basket &lt; Hoodoo::Presenters::Base
  schema do
    array :items do
      type BasketItem
    end
  end
end
</code></pre>

<p>A fragment of JSON for a basket might look like this:</p>

<pre><code>{
  &quot;items&quot;: [
    {
       // (First BasketItem&#39;s fields)
    },
    {
       // (First BasketItem&#39;s fields)
    },
    // etc.
  ]
}</code></pre>

<p>Example 2 - a basket item refers to a product description by having its
fields inline. So suppose we have this:</p>

<pre><code>class Product &lt; Hoodoo::Presenters::Base
  schema do
    internationalised
    text :name
    text :description
  end
end

class BasketItem &lt; Hoodoo::Presenters::Base
  schema do
    object :product_data do
      type Product
    end
  end
end
</code></pre>

<p>…then this would be a valid BasketItem fragment of JSON:</p>

<pre><code>{
  &quot;product_data&quot;: {
    &quot;name&quot;: &quot;Washing powder&quot;,
    &quot;description&quot;: &quot;Washes whiter than white!&quot;
  }
}
</code></pre>

<p>It is also possible to use this mechanism for inline expansions when you
have, say, a Resource defined <em>entirely</em> in terms of something
reused elsewhere as a Type. For example, suppose the product/basket
information from above included information on a Currency that was used for
payment. It might reuse a Type; meanwhile we might have a resource for
managing Currencies, defined entirely through that Type:</p>

<pre><code>class Currency &lt; Hoodoo::Presenters::Base
  schema do
    string :curency_code, :required =&gt; true, :length =&gt; 8
    string :symbol, :length =&gt; 16
    integer :multiplier, :default =&gt; 100
    array :qualifiers do
      string :qualifier, :length =&gt; 32
    end
  end
end

resource :Currency do
  schema do
    type Currency # Fields are *inline*
  end
end
</code></pre>

<p>This means that the <strong>Resource</strong> of <code>Currency</code> has
exactly the same fields as the <strong>Type</strong> of Currency. The
Resource could define other fields too, though this would be risky as the
Type might gain same-named fields in future, leading to undefined
behaviour. At such a time, a degree of cut-and-paste and removing the
<code>type</code> call from the Resource definition would probably be wise.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-type_source')" id="l_method-i-type_source">show</a>
              </p>
              <div id="method-i-type_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/presenters/base_dsl.rb, line 379</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">type</span>( <span class="ruby-identifier">type_info</span>, <span class="ruby-identifier">options</span> = <span class="ruby-keyword">nil</span> )
  <span class="ruby-identifier">options</span> <span class="ruby-operator">||=</span> {}

  <span class="ruby-keyword">if</span> <span class="ruby-identifier">type_info</span>.<span class="ruby-identifier">is_a?</span>( <span class="ruby-constant">Class</span> ) <span class="ruby-operator">&amp;&amp;</span> <span class="ruby-identifier">type_info</span> <span class="ruby-operator">&lt;</span> <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Presenters</span><span class="ruby-operator">::</span><span class="ruby-constant">Base</span>
    <span class="ruby-identifier">klass</span> = <span class="ruby-identifier">type_info</span>
  <span class="ruby-keyword">else</span>
    <span class="ruby-keyword">begin</span>
      <span class="ruby-identifier">klass</span> = <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Data</span><span class="ruby-operator">::</span><span class="ruby-constant">Types</span>.<span class="ruby-identifier">const_get</span>( <span class="ruby-identifier">type_info</span> )
    <span class="ruby-keyword">rescue</span>
      <span class="ruby-identifier">raise</span> <span class="ruby-node">&quot;Hoodoo::Presenters::Base\#type: Unrecognised type name &#39;#{ type_info }&#39;&quot;</span>
    <span class="ruby-keyword">end</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">instance_exec</span>( <span class="ruby-operator">&amp;</span><span class="ruby-identifier">klass</span>.<span class="ruby-identifier">get_schema_definition</span>() )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-uuid">
              <b>uuid</b>( field_name, options = nil )
            <a href="../../../classes/Hoodoo/Presenters/BaseDSL.html#method-i-uuid" name="method-i-uuid" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Declares that this Type or Resource _refers to_ another Resource instance
via its <a href="UUID.html">UUID</a>. There&#39;s no need to declare the
presence of the <a href="UUID.html">UUID</a> field _for the instance
itself_ on all resource definitions as that&#39;s implicit; this <a
href="BaseDSL.html#method-i-uuid">uuid</a> method is just for relational
information (AKA associations).</p>
<dl class="rdoc-list note-list"><dt><code>field_name</code>
<dd>
<p>Name of the field that will hold the <a href="UUID.html">UUID</a>.</p>
</dd><dt><code>options</code>
<dd>
<p>Options hash. See below.</p>
</dd></dl>

<p>In addition to standard options from <a
href="BaseDSL.html">Hoodoo::Presenters::BaseDSL</a>, extra option keys and
values are:</p>
<dl class="rdoc-list note-list"><dt><code>:resource</code>
<dd>
<p>The name of a resource (as a symbol, e.g. <code>:Product</code>) that the
<a href="UUID.html">UUID</a> should refer to. Implementations <em>may</em>
use this to validate that the resource, where a <a
href="UUID.html">UUID</a> is provided, really is for a Product instance and
not something else. Optional.</p>
</dd></dl>

<p>Example - a basket item that refers to an integer quantity of some specific
Product resource instance:</p>

<pre><code>class BasketItem &lt; Hoodoo::Presenters::Base
  schema do
    integer :quantity, :required =&gt; true
    uuid :product_id, :resource =&gt; :Product
  end
end
</code></pre>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-uuid_source')" id="l_method-i-uuid_source">show</a>
              </p>
              <div id="method-i-uuid_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/presenters/base_dsl.rb, line 272</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">uuid</span>( <span class="ruby-identifier">field_name</span>, <span class="ruby-identifier">options</span> = <span class="ruby-keyword">nil</span> )
  <span class="ruby-identifier">options</span> <span class="ruby-operator">||=</span> {}
  <span class="ruby-identifier">property</span>(<span class="ruby-identifier">field_name</span>, <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Presenters</span><span class="ruby-operator">::</span><span class="ruby-constant">UUID</span>, <span class="ruby-identifier">options</span>)
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
</div>

    </div>
  </body>
</html>
